GetPromiseValue

Inside Macintosh: OpenDoc Class Reference /: Part 1 - Classes and Methods / ODStorageUnitView

GetPromiseValue
The GetPromiseValue method reads promise data from the specified value of the focused property.
ODULong GetPromiseValue (in ODValueType valueType,
                         in ODULong offset,
                         in ODULong length,
                         out ODByteArray value,
                         out ODPart sourcePart);
valueType
The type of the value from which the promise data is to be read.
offset
The offset from which the promise data is to be retrieved, expressed as an unsigned 32-bit number of bytes from the beginning of the value.
length
The length (in bytes) of the data to be retrieved, expressed as an unsigned 32-bit value.
value
A byte array structure to contain the retrieved promise data.
sourcePart
A reference to the part that made the promise.
return value
The number of bytes read, expressed as an unsigned 32-bit value.

DISCUSSION
You call this method to read promise data without fulfilling the promise. This method first focuses the storage unit on the specified value of the focused property. It then starts reading data at the specified offset and stops after reading the number of bytes specified by the length parameter or after reaching the end of the data in the focused value, whichever comes first.
When you call this method, the _buffer field of the value output parameter should be kODNULL; if it isn't, the buffer to which that field points will not be deallocated.
This method sets the _buffer field of the value output parameter to point to a memory block containing the promise data, the _maximum field to the specified length, and the _length field to the number of bytes actually read.
This method sets the sourcePart output parameter to a reference to the part that made the promise. This method does not increment the reference count of the part that made the promise.
When you no longer need the structure you pass as the value parameter, you should deallocate that structure and its buffer.

EXCEPTIONS

kODErrInvalidValueType
The specified value type is improperly formed or illegal.
kODErrSUValueDoesNotExist
The focused property does not have a value with the specified value type.
kODErrUnfocusedStorageUnit
The focus context of this storage-unit view is not a property or a value.
If the storage-unit cursor for this storage-unit view does not represent a legal focus context for the storage unit that created this storage-unit view, this method throws exceptions raised by the FocusWithCursor method of that storage unit.

SEE ALSO
The ODByteArray type (page 877).
The ODValueType type (page 904).
The ODStorageUnitView::IsPromiseValue method (page 750).
The ODStorageUnitView::SetPromiseValue method (page 757).